Allows your application to control various settings in Navigation Services dialog boxes.

OSErr NavCustomControl (
    NavContext context, 
    NavCustomControlMessage selector, 
    void *parms
);

context

A value set by your application to provide context. When Navigation Services processes your NavCustomControl call and, in turn, calls your event-handling function, you can obtain this value from the context field of the structure of type NavCBRec specified in the callBackParms parameter of your event-handling function.

selector

A value of type NavCustomControlMessage. Pass one or more of the constants representing the possible values used to control various aspects of the active dialog box. For a description of these constants, see “Custom Control Setting Constants”.

parms

A pointer to a configuration value. Some of the control setting constants passed in the selector parameter require that you provide an additional configuration value. For a description of which constants require configuration values, see “Custom Control Setting Constants”.

function result

A result code.

DISCUSSION

If you have provided an event-handling function and an event occurs in a Navigation Services dialog box, Navigation Services calls your event-handling function and specifies one of the constants described in “Event Message Constants” in the param field of a structure of type NavCBRec. Navigation Services specifies this structure in the callBackParms parameter of your event-handling function. When Navigation Services supplies the kNavCBStart constant in the param field, your application can call the NavCustomControl function and pass one of the constants described in “Custom Control Setting Constants” to control various aspects of the active Navigation Services dialog box. For example, your application can tell Navigation Services to sort the browser list by date by calling the NavCustomControl function and passing the kNavCtlSortBy constant in the selector parameter and a pointer to the kNavSortDateField configuration constant in the parms parameter. (Some of the NavCustomControlMessage constants do not require a corresponding configuration constant.)

Navigation Services does not accept calls to the NavCustomControl function until an appropriate dialog box is fully initialized and displayed. Always check for the kNavCBStart constant, described in “Event Message Constants”, in the param field of the NavCBRec structure before calling the NavCustomControl function.

Note that your application can call the NavCustomControl function from within its event-handling function or its preview-drawing function.

See also “Adding Custom Controls” and “Handling Events”.

SPECIAL CONSIDERATIONS

Navigation Services does not accept calls to the NavCustomControl function until an appropriate dialog box is fully initialized and displayed. Always check for the kNavCBStart constant, described in “Event Message Constants”, in the param field of the NavCBRec structure before calling the NavCustomControl function.

Note that your application can call the NavCustomControl function from within its event-handling function or its preview-drawing function.

VERSION NOTES

Available in Navigation Services 1.0 and later.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when NavigationLib 1.0 or later is installed. Exported by CarbonLib 1.0 and later and by NavigationLib 1.0 and later.

© 2000 Apple Computer, Inc. — (Last Updated 4/17/2000)